home *** CD-ROM | disk | FTP | other *** search
/ Shareware for Windows / Trust Shareware CD.iso / winshare / vb / mlist / read.me < prev   
Encoding:
Text File  |  1993-11-25  |  17.1 KB  |  450 lines
  1. ***************************************************************************
  2. *
  3. *  McKean Consulting
  4. *  Robin W. McKean
  5. *  1042 Braddock Circle
  6. *  Woodstock GA  30188
  7. *
  8. *  MLIST.VBX    V4.02.0000
  9. *
  10. *  Multi-Purpose List Box Control for Visual Basic 3.0
  11. *
  12. ***************************************************************************
  13.  
  14. MLIST is a custom control for managing the way your data appears in a list
  15. box.  MLIST is a property for property replacement of the standard List Box
  16. control which comes with Visual Basic 3.0.  In addition, there are many more
  17. features which MLIST can do that you can't do with the normal List Box.  Some
  18. of these features are:
  19.  
  20.     * Set up owner draw columnar data in the list box.  This is NOT a
  21.       MULTI-COLUMN list box.  MLIST now has this feature, but the MLIST
  22.       List Box scrolls vertically, like a normal list box.  Your data is
  23.       arranged in columns, with specific drawing flags setup for each
  24.       "Drawing Region".  Think of each line as being broken up into
  25.       different areas, each with its own drawing flags and data.
  26.  
  27.     * Make a drawing region a bitmap or a checkbox.  You have control
  28.       over the entire list's bitmaps through the default bitmap property,
  29.       or you can set individual lines bitmap properties.
  30.  
  31.     * Control individual line colors in the list box
  32.  
  33.     * Total control over the checked and unchecked states of lines
  34.  
  35.     * Now MLIST has aligned bitmaps as well.  You specifiy the bitmap,
  36.       the text, and the alignment (top, bottom, right, left), and MLIST
  37.       will draw the text and the bitmap in the area you define.
  38.  
  39.     * New in verions 4.00.  You can now have true MUTLIPLE COLUMN list
  40.       boxes, with bitmaps and check boxes.  Multiple columns are set
  41.       up through setting the LBS_MULTICOLUMN style for the list box.
  42.       You control the width of each item.  This attribute differs in
  43.       that each line has a certain width.  So it may take two or more
  44.       columns of items to actually fill a line
  45.  
  46.     * Checking and Selecting a range of line items
  47.  
  48.     * Properties to find closest match and find exact matches in the
  49.       list box.
  50.  
  51. ***************************************************************************
  52.  
  53. This ZIP file contains:
  54.  
  55.     MLIST.VBX         VB version of the MLIST custom control
  56.     PROJECT1.MAK    Sample project file for MLIST
  57.     FORM1.FRM        Form used by the sample project
  58.     READ.ME            This file
  59.     PLUS.BMP        Bitmap used in example
  60.     PAGE.BMP        Ditto
  61.  
  62. ***************************************************************************
  63.  
  64. REGISTRATION
  65.  
  66. Time for the sob story.  This Multi-Column List Box is Shareware.  It is
  67. NOT crippled in anyway.  When you download this custom control, you have
  68. the same custom control that I am using in my everyday VB programming.
  69. As a Shareware contributor, I am counting on the honor and moral fiber of
  70. every person who downloads this custom control to do the right thing.  I
  71. have contributed and participated in the Shareware arena for years now.
  72. Your small contribution can make a difference to me and my family...  
  73.  
  74. Right now, the maximum string size in the List Box is 255 characters.  Let me
  75. know if this causes a problem.  I don't anticipate anyone needing to display
  76. more than this number of characters to the screen.
  77.  
  78. If you like and appreciate this custom control...
  79.  
  80.   1)  Small time developers like me, send $10.00 to the address listed above
  81.   2)  Corporate users send $15.00 to the address listed above
  82.   3)  Register in the Compuserve SWREG forum ID 1585
  83.  
  84. Registered users may purchase the source...
  85.  
  86.   Send $25.00 to me at the above address.
  87.  
  88.   This control is written in C and has been compiled using both Borland C++
  89.   3.1 and Visual C++ 1.0.
  90.  
  91. You may now register this control in the SWREG on Compuserve.  Type GO SWREG.
  92. If you want the source, you will still have to write me...
  93.  
  94. Corporate users should register via mail.
  95.  
  96. ***************************************************************************
  97.  
  98. WARRANTY
  99.  
  100. The control, as is, works the way that I want it to.  This does not mean
  101. that it will work the way that you want it to.   Along those lines, I
  102. totally disclaim that the control will do anything whatsoever.  This
  103. includes any implied abilities and any WARRANTIES, including those for
  104. SUITABILITY for a particular purpose, MERCHANTIBILITY, and all that other
  105. bull crap.
  106.  
  107. ***************************************************************************
  108.  
  109. PROGRAMMER'S NOTES (or, what I need to know to use this custom control)
  110.  
  111. The Multi-Column List Box is an enhanced List Box control.  The following
  112. is a desciption of each additional control.  What it does, and how to
  113. use it in your own VB programming.  For additional control properties, see
  114. those for properties included in the standard list box control.  MLIST now
  115. contains all standard controls.  The ones listed below are additions.
  116.  
  117. ItemHeight
  118.  
  119. This property is responsible for controlling the height of each individual
  120. line item in the list box.  It defaults to 195 Twips, the height of the
  121. font used by the standard list box.  You should adjust this height if you
  122. change the font, font size, etc..
  123.  
  124. I'm not sure whether or not this property will change the height of the lines
  125. after the list box has already been created.  I did not design the list box
  126. control to have the height of the items change dynamically.  Set the height
  127. of this item at design time, and the font, and your list box will be fine.
  128. Experiment with this during run-time if you like, and let me know how it
  129. works out, and how I can make this item work more to your liking.
  130.  
  131. DrawRegions
  132.  
  133. This item determines the number of drawing regions on each line.  This is
  134. basically equivelent to the number of COLUMNS, but this list box will still
  135. scroll like a normal list box.  When setting this property, the control
  136. clears the flags for the draw regions and sets them to left aligned, single
  137. line, and centered vertically.  Consult the Windows API for DrawText to
  138. see what exactly these flags mean.
  139.  
  140. ItemLength
  141.  
  142. This is an indexed property which corresponds to the length of each drawing
  143. region.  If you want a drawing region to be a specific length, set that
  144. drawing region's length to the desired setting in twips.  For example...
  145.  
  146.     MList1.DrawRegions = 2
  147.     MList.ItemLength(1) = 500
  148.     MList.ItemLength(2) = 500
  149.  
  150.     ' Generates an out of index error
  151.     MList1.ItemLength(0) = XXX
  152.     MList1.ItemLength(3) = XXX
  153.  
  154. It is probably a good idea to set the lengths of all drawing regions when you
  155. are changing the defaults.
  156.  
  157. DrawFlags
  158.  
  159. This is an indexed property which corresponds to the flags of each drawing
  160. region.  If you want a drawing region to be drawn in a specific manner, set
  161. that drawing region's flags to the desired settings.  For specific flags,
  162. look up the DrawText API function in the Windows API Reference.  In the
  163. following example, I setup two drawing regions and set the second drawing
  164. region's flags to right justify the text.  In this example, the second
  165. drawing region displays currency values.
  166.  
  167.     Const DT_RIGHT = 2
  168.     Const DT_VCENTER = 4
  169.     Const DT_SINGLELINE = 32
  170.  
  171.     MList1.DrawRegions = 2
  172.     MList1.Flags(2) = DT_RIGHT + DT_VCENTER + DT_SINGLELINE
  173.     MList.ItemLength(1) = 500
  174.     MList.ItemLength(2) = 500
  175.  
  176. ActiveRegion
  177.  
  178. Setting this property affects the next two properties.  It defines the
  179. DrawingRegion (or index or column) that TextRegion and ListRegion will
  180. return.  Perhaps an example is in order.
  181.  
  182. My list box is divided up into three columns, name, account number, dollar
  183. amount.  I want to get the account number for the currently selected line
  184. as well as the first item...
  185.  
  186.     MList1.ActiveRegion = 2
  187.     aString$ = MList1.TextRegion    ' Gets 2nd column of current text
  188.     bString$ = MList1.ListRegion(0)    ' 2nd column of item at index 0
  189.  
  190. TextRegion
  191.  
  192. This property will return the ActiveRegion in the currently selected text.
  193. See the above "ActiveRegion".  Corresponds to a DrawRegion of the Text property.
  194. These values can also be written to at run time.
  195.  
  196. ListRegion
  197.  
  198. This property will return the ActiveRegion in the item at the specific index.
  199. See the above "ActiveRegion".  Corresponds to a DrawRegion of the List property.
  200. These values can also be written to at run time.
  201.  
  202. DefPicture
  203.  
  204. This is the default bitmap to be displayed in the ImageRegion when a specific
  205. bitmap has not been assigned to that items ItemPicture property.  Please see
  206. the demo on setting your own default picture and ItemPicture properties.
  207.  
  208. ImageType
  209.  
  210. This determines what type of image we are dealing with in our image region.
  211. If this property is set to 0, then the ImageRegion property is ignored and
  212. only text is dislayed.  If this image type is valid, then a checkbox or
  213. bitmap is displayed in the ImageRegion.
  214.  
  215. Note that when the image type is set to AlignBitmap, the normal drawing
  216. regions no longer apply.  Anybody got a problem with that???
  217.  
  218. ImageRegion
  219.  
  220. This property specifies which region contains the image region.  This value
  221. should be any number between 1 and the number of DrawRegions.  You may not
  222. set this property to a value of less than zero or greater then DrawRegions.
  223. When setting up your DrawRegions, the following is a good example:
  224.  
  225.     MList1.DrawRegions = 3
  226.     MList1.ImageRegion = 1
  227.  
  228.     MList1.ItemLength(1) = 100        ' Bitmap is in here
  229.     MList1.ItemLength(2) = 500
  230.     MList1.ItemLength(3) = 750
  231.  
  232.     ' Don't leave a space for the ImageRegion in your strings
  233.     MList1.AddItem "Region2" + Chr$(9) + "Region3"
  234.     MList1.AddItem "Region22" + Chr$(9) + "Region33"
  235.  
  236. The ImageRegion is ignored when calculating the "piece" of text that goes in
  237. that region.
  238.  
  239. Checked
  240.  
  241. This property is very similar to the Selected property.  In a Multi-Column
  242. list box with the ImageType set 2 (CheckBox), this property will return to
  243. you whether or not that line item is checked or not.  For example:
  244.  
  245.     For X% = 0 To MList1.ListCount - 1
  246.  
  247.         If MList1.Checked(X%) Then
  248.             Debug.Print "I am Checked! "; X%
  249.         Else
  250.             Debug.Print "I am not checked! "; X%
  251.         End If
  252.     Next X%
  253.  
  254.     ' Check the first item
  255.     MList1.Checked(0) = True
  256.  
  257. ItemPicture
  258.  
  259. This property is an array of pictures which correspond to the bitmaps for
  260. each line item in the list box.  If this item is not set by you, then
  261. the MList uses the DefPicture property.
  262.  
  263.     ' Change the first items picture in the list box
  264.     MList1.ItemPicture(0) = Image1.Picture
  265.  
  266. ItemForeColor
  267.  
  268. This property is an array of color which correspond to the foreground color
  269. for each line item in the list box.  If this item is not set by you, then
  270. the MList uses the default foreground color property.
  271.  
  272.     ' Change the first items foreground color to white
  273.     MList1.ItemForeColor(0) = RGB(255,255,255)
  274.  
  275. ItemBkColor
  276.  
  277. This property is an array of color which correspond to the background color
  278. for each line item in the list box.  If this item is not set by you, then
  279. the MList uses the default background color property.
  280.  
  281.     ' Change the first items background color to black
  282.     MList1.ItemBkColor(0) = RGB(0,0,0)
  283.  
  284. Alignment
  285.  
  286. This property controls the placement of the bitmap when the image type is
  287. set to 4, AlignBitmap.  See the demo for details, but basically the values
  288. for this property are:
  289.  
  290. 1 - Align the bitmap to the left, centered, then the text, centered
  291.     vertically and left justified.
  292. 2 -    Align the bitmap on top, centered, then the text, centered
  293.     horizontally and vertically.
  294. 3 - Align the bitmap to the right, centered, then the text, centered
  295.     vertically and left justified.
  296. 4 -    Align the bitmap on bottom, centered, then the text, centered
  297.     horizontally and vertically.
  298.  
  299. Note that when the image type is set to AlignBitmap, the normal drawing
  300. regions no longer apply.  Anybody got a problem with that???
  301.  
  302. MultiColumn
  303.  
  304. This turns the list box into a true multiple column list box.  The list box
  305. will scroll horizontal instead of vertical.  A default item width is provided,
  306. but you, the developer, should override this property.  This property should
  307. be set to true for multi-column, or false (the default) for normal list box
  308. behavior.
  309.  
  310. ItemWidth
  311.  
  312. The property specifies the width of each line in a multiple column list box.
  313. The width is set in Twips.  The normal drawing regions still apply, but I
  314. can't think of a reason why someone would want to divide line items in a 
  315. column list box into more columns.
  316.  
  317. FindString
  318.  
  319. Setting this property will cause the list box to search for a string with
  320. the closest match from the current ListIndex.  If one is found, that string
  321. is set to the current ListIndex.  This is useful for moving items through
  322. a list box while typing the string in an edit control, ie.  Search in Help.
  323.  
  324. FindStringExact
  325.  
  326. This property is the same as above, except that it will search for an exact
  327. match.
  328.  
  329. RangeStart
  330.  
  331. This property marks the beginning line item for RangeSelected or RangeChecked.
  332. The offset is 0 based, so the first item is 0.
  333.  
  334. RangeEnd
  335.  
  336. This property marks the ending line item for RangeSelected or RangeChecked.
  337.  
  338. RangeSelected
  339.  
  340. All items in the range RangeStart to RangeEnd are marked as selected in the
  341. list box.  If the list box is not multi-select, then this is ignored.
  342.  
  343.     MList1.RangeStart = 0
  344.     MList1.RangeEnd = 3
  345.     MList1.RangeSelected = True
  346.  
  347. RangeChecked
  348.  
  349. All items in the range RangeStart to RangeEnd are marked as checked in the
  350. list box.
  351.  
  352.     MList1.RangeStart = 0
  353.     MList1.RangeEnd = 3
  354.     MList1.RangeChecked = False
  355.  
  356. SetHzScroll
  357.  
  358. When all is said and done, and you are through setting up your list box, and
  359. your columns extend past the displayable area of the list box, setting this
  360. property to True will cause the MLIST control to add up all of the drawing
  361. regions and add a horizontal scroll bar to the list box if one is neccessary.
  362.  
  363. ***************************************************************************
  364.  
  365. FORMATTING STRINGS
  366.  
  367. You should place the Tab character between each column in your string.  The
  368. following example formats a string for the DrawFlags example:
  369.  
  370.     MList1.AddItem "Robin W. McKean" + Chr$(9) + "$100.00"
  371.  
  372. The following string is for three columns:
  373.  
  374.     MList1.AddItem "Robin W. McKean"+Chr$(9)+"$100.00"+Chr$(9)+"True"
  375.  
  376. Remember, you do NOT have to include a column for the ImageRegion.  If
  377. the ImageRegion property was 1 and the DrawRegions property was 3, then
  378. the following line would work fine (3-1=2)
  379.  
  380.     MList1.AddItem "Robin W. McKean"+Chr$(9)+"$100.00"
  381.  
  382. ***************************************************************************
  383.  
  384. REACHING THE AUTHOR
  385.  
  386. I can be reached via U.S. Mail at the address listed above.  You can reach
  387. me via E-Mail at the following locations...
  388.  
  389. Compuserve:            Robin W. McKean
  390.                     72622,1403
  391.  
  392. Shareware South:    Robin W. McKean
  393.                     Atlanta, GA
  394.  
  395. I'm on Compuserve once or twice a day.  I check Shareware South about once
  396. a week.
  397.  
  398. ***************************************************************************
  399.  
  400. REVISION HISTORY
  401.  
  402. 3.00.0000    Initial release of the MLIST.VBX Custom Control
  403. 3.01.0000    Fixed "Bad Index" error message when setting Selected
  404.             property to True|False.
  405.             Added ItemData property to control.
  406.             Added ListIndex property to control.
  407.             Fixed an apparent bug in the VB API that was passing right
  408.             mouse button clicks to the Click event, but not the left
  409.             mouse button.
  410. 3.02.0000    Fixed a ton of problems.  Namely, the page down didn't work.
  411.             Delete current controls and rebuild to fix this problem.
  412.             Added ALL default controls for the standard list box.
  413.             Tested all of them before uploading.
  414. 3.03.0000    Fixed the index problem with the List property.  If anything,
  415.             I am guilty of being over enthusiastic.  I apologize to those
  416.             who got the previous version and thought it sucked.  Probably
  417.             because it did.  I added bitmaps and checkboxes as well as
  418.             the ability to change the color of a specific line.  You can
  419.             also change the bitmap of a specific line item.
  420. 3.04.0000    Fixed the bug with setting the Checked property, and then not
  421.             having the user be able to double click it or click the box
  422.             to change it back.  Added the AlignBitmap image type and
  423.             the Alignment property.
  424. 4.00.0000    Added the Multicolumn property and item width.  Added the
  425.             FindString and FindStringExact properties for searching
  426.             the list box.  Added the range properties for checking
  427.             and selecting multiple line items.
  428. 4.01.0000    Removed the 64k limit.  MLIST will now allow more than 64k
  429.             worth of data to be added to it.  Also, quit handling default
  430.             methods, such as Move (which didn't work), Refresh, and others.
  431.             Fixed problem with RemoveItem not deleting lines data.
  432.             Changing the way MLIST handled strings did the job.
  433. 4.02.0000    Removed a bug which caused a GP fault when more than 16 drawing
  434.             regions were requested by the user.  Reworked VB2.0 compatibility
  435.             strategy.
  436.  
  437. ***************************************************************************
  438.  
  439. ACKNOWLEDGEMENTS
  440.  
  441. I would like to thank Simon, Kevin, and Neil for their input.  A great C++
  442. programmer does not a good VB programmer make...  Please, Please, Please,
  443. take a few minutes to notify me if there are any bugs.  I hate bugs...
  444.  
  445. Thanks to Paul for the check box problem.
  446.  
  447. Thanks to Alex for providing info on VB 2.0 problems.
  448.  
  449. ***************************************************************************
  450.